                        ===========
                        R E A D M E
                        ===========

    QLogic Ethernet Controller CMPI provider for Linux

            Copyright (c) 2015 QLogic Corporation
                     All rights reserved.

Table of Contents
-----------------

    1.  Overview
    2.  Limitation
    3.  Dependency
    4.  Files
    5.  Installation
    6.  Uninstall - RPM package
    7.  Software Update Profile
    8.  Known Limitations
    9.  Troubleshooting
   10.  Third Party Software License



1. Overview
-----------

QLogic ethernet controller CMPI provider for Linux is designed
to provide information and basic diagnostics functions for QLogic
made ethernet controllers.
Implementation of the provider uses BMAPI to collect information and
perform actual diagnostics functions for network controllers.



2. Limitation
-------------

The provider supports PowerPC 64 bit and i386 architecture based CPU. 
The following is the list of supported OS:

    SuSE Linux Enterprise Server(SLES) 10 32 and 64 bit
    SuSE Linux Enterprise Server(SLES) 11 32 and 64 bit
    Redhat Enterprise Linux Redhat 5 32 and 64 bit
    Redhat Enterprise Linux Redhat 6 32 and 64 bit

Please also refer to 'Dependency' section for more information.



3. Dependency
------------------

a. QLogic network adapters running the following driver versions:
   For NetXtreme devices:      tg3   >= 3.37.
   For NetXtremeII devices:    bnx2  >= 1.9.3.
   For iSCSI and FCoE support: NX2 driver package >= 7.0.35

   Please refer to README.TXT of the target driver for installation
   instruction.

b. BMAPI
   bmapilnx version >= 6.16.0.

c. OpenPegasus
   This provider package is tested with OpenPegasus 2.9.2, 2.10.0, and 2.11.1 
   compiled from source code. The distributed version of inbox Pegasus found 
   in Redhat 5 and Redhat 6 has also been verified. There is no inbox Pegasus 
   for SuSE.

d. iSCSI and FCoE Support
   For iSCSI and FCoE support, the following additional packages 
   from the OS should be installed:
     - open-iscsi utilities available for the the OS
     - sg3_utils


4. Files
--------
    
    libbmapi.so.{version}                       BMAPI share library
    libQLGCCmpiProvider.so                       QLGC_CIM provider library
    BnxAdapter.mof                              MOF file
    BnxCDM.mof                                  MOF file
    BnxCmpiProvier.mof                          MOF file
    BnxCmpiProvierReg.mof                       MOF file
    readme.txt                                  this file
    release.txt                                 release information


5. Installation
---------------

    a. Read 'Dependency' section and make sure required packages are
       installed properly.

    b. Obtain OpenPegasus package (v2.10.0 or later) from www.openpegasus.org.

    c. Set the following environment variables for OpenPegasus:
           PEGASUS_ROOT - this is the location of the pegasus source tree.
           PEGASUS_HOME - this is the location for the built executables,
                          and repository to contain $PEGASUS_HOME/bin, 
                          $PEGASUS_HOME/lib, $PEGAUS_HOME/repository,
                          and $PEGASUS_HOME/mof subdirectories.
           PEGASUS_ENABLE_CMPI_PROVIDER_MANAGER=true
           PEGASUS_CIM_SCHEMA="CIM222"
           
           PEGASUS_PLATFORM="LINUX_IX86_GNU"   (for 32 bit systems)
           PEGASUS_PLATFORM="LINUX_X86_64_GNU" (for 64 bit systems)

    d. Build OpenPegasus properly with the following commands: 
          % make clean; make
          % make repository 
       ** It has been observed that compilation of Pegasus failed on 
       SLES 11 system due to missing header files. Please contact 
       the System Administrator to make sure the header files Pegasus
       depends on are installed.

    e. Install the RPM package as: 
          % rpm -i QLGC_CMPIProvider-{version}.{arch}.rpm

       Note: If the cimserver is running, it will be brought down 
             during the installation and re-started upon completion 
             of the installation.

    f. Start cimserver if necessary.


6. Uninstall - RPM package
---------------------------

    To uninstall RPM package as:
       % rpm -e QLGC_CMPIProvider



7. Software Update Profile
---------------------------
   For Software Update Profile, CIM_SoftwareInstallationService.InstallFromURI() 
   method is implemented to support firmware upgrade. This function takes the 
   following parameters:
   1. URI - the USRI corresponding to the new firmware image to be used.
   2. Target - reference to the CIM_SoftwareIdentity corresponding to the 
               device and firmware to be upgraded.
   3. InstallOptions - supports options "defer reset" (2), "force" (3),
                       "update" (5), "reboot" (7) and QLogic specific 
                       values 32768 and 32769.
   4. InstallOptionsValues - if QLogic specific values 32768 or 32769 are used in 
                       InstallOptions array, there should be an entry in 
                       InstallOptionValues array with the same index of the QLogic
                       specific value in the InstallOptions array.
                       e.g. if the 2nd entry of InstallOptions contains 32768, then 
                       the 2nd entry of InstallOptionsValue should contain an option 
                       string accordingly.
                       "-p" to upgrade iSCSI configuration program along with iSCSI 
                       firmware.

   For iscsi firmware upgrade, the following 2 entries in InstallOptions/InstallOptionsValues 
   are supported:
       InstallOptions    InstallOptionsValues           Required    Purpose
   -----------------------------------------------------------------------------------------------
   1.  32768             "-p"                           No          upgrade iscsi config program
                                                                    along with iscsi firmware
   2.  32769             "ipv4", "ipv6", or "ipv4n6"    Yes         specify the iscsi configuration
                                                                    for the upgrade 
   If option 32769 and the corresponding value is not specified when upgrading iscsi firmware, 
   InstallFromURI() method will return error. 


8.  Known Limitations
----------------------

   Enumerating all instances at one time is not working. Only 
   enumeration of instances for individual classes is supported. 


9. Troubleshooting
-------------------

Problem:        Cannot enumerate any QLGC classes

Possible cause: Provider software is not installed properly.
Solution:       Reinstall provider software and make sure the bnxCmpiProvider, 
                BmapiObjServices, and BrcmUtil libraries are in the library 
                search path.

Possible cause: Bmapi library is not in the library search path, or the wrong 
                version of Bmapi library is installed.
Solution:       Make sure a supported version of Bmapi library is in the library 
                search path. Refer to Dependency section for supported versions 
                of Bmapi.


Problem:        No QLogic devices are enumerated.

Possible cause: Device driver of supported version is not installed or not loaded.
Solution:       Make sure the device driver is installed and loaded properly.
                Ethtool should be able to enumerate the device if driver is installed.
                Refer to Dependency section for supported versions of device drivers.


Problem:        RunDiagnostic failed 

Possible cause: Ran out of disk/memory space.
Solution:       Free up disk/memory space and try again.

Possible cause: No admin privileges to run the tests.
Solution:       Login as administrator and try again.

Possible cause: Device is already in diagnostic state.
Solution:       Wait until the current diagnostic to finish and try again.


If the problem can't be solved by any of the above, and it is persistent, 
try using a different version of driver or software and repeat the test to 
rule out the possibility of faulty software.
If the problem still persists, contact support personnel and ask for support.


10. Third Party Software License
--------------------------------

Portions of this software contain third party code subject to the following conditions:

OpenSSL

/* ====================================================================
 * Copyright (c) 1998-2007 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

 Original SSLeay License
 -----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
 * All rights reserved.
 *
 * This package is an SSL implementation written
 * by Eric Young (eay@cryptsoft.com).
 * The implementation was written so as to conform with Netscapes SSL.
 *
 * This library is free for commercial and non-commercial use as long as
 * the following conditions are aheared to.  The following conditions
 * apply to all code found in this distribution, be it the RC4, RSA,
 * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
 * included with this distribution is covered by the same copyright terms
 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
 *
 * Copyright remains Eric Young's, and as such any Copyright notices in
 * the code are not to be removed.
 * If this package is used in a product, Eric Young should be given attribution
 * as the author of the parts of the library used.
 * This can be in the form of a textual message at program startup or
 * in documentation (online or textual) provided with the package.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *    "This product includes cryptographic software written by
 *     Eric Young (eay@cryptsoft.com)"
 *    The word 'cryptographic' can be left out if the routines from the library
 *    being used are not cryptographic related :-).
 * 4. If you include any Windows specific code (or a derivative thereof) from 
 *    the apps directory (application code) you must include an acknowledgement:
 *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
 *
 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * The license and distribution terms for any publically available version or
 * derivative of this code cannot be changed.  i.e. this code cannot simply be
 * copied and put under another distribution license
 * [including the GNU Public License.]
 */


Tcl/Tk License Terms

/* This software is copyrighted by the Regents of the University of California, 
 * Sun Microsystems, Inc., Scriptics Corporation, and other parties. The following 
 * terms apply to all files associated with the software unless explicitly disclaimed 
 * in individual files.
 * 
 * The authors hereby grant permission to use, copy, modify, distribute, and license 
 * this software and its documentation for any purpose, provided that existing copyright 
 * notices are retained in all copies and that this notice is included verbatim in any 
 * distributions. No written agreement, license, or royalty fee is required for any of 
 * the authorized uses. Modifications to this software may be copyrighted by their authors 
 * and need not follow the licensing terms described here, provided that the new terms 
 * are clearly indicated on the first page of each file where they apply.
 * 
 * IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, 
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF 
 * THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS 
 * HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, 
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" 
 * BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, 
 * SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 * 
 * GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, 
 * the Government shall have only "Restricted Rights" in the software and related 
 * documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 
 * 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, 
 * the software shall be classified as "Commercial Computer Software" and the Government 
 * shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. 
 * Notwithstanding the foregoing, the authors grant the U.S. Government and others acting 
 * in its behalf permission to use and distribute the software in accordance with the terms 
 * specified in this license. 
 */


